注释和缩进编排

  明智地使用注释，一致性地使用缩进编排形式，可以使阅读和理解一个程序的工作变得更愉快些。人们经常采用的几种不同的一致性缩进编排风格。我看不出偏爱某种风格胜过另一种的明显理由（虽然像大多数程序员一样，我也有我的偏爱，本书就反应了有关的情况）。这一点也同样适用于注释风格。

  注释可能被人们以许多方式误用，并因此严重地影响程序的可读性。编译器当然不会理解注释的内容，因此它无法保证一个注释

1）、是有意义的
2）、描述了这个程序
3）、是符合目前情况的。

许多程序里都包含着不易理解的、歧义的，或者根本就是错误的注释。糟糕的注释还不如没有注释。

  如果某些东西已经由语言本身说明白，那么就不应当再作为注释中提及的内容。这个说法针对的就是下面这一类东西：

// 变量 "v" 必须初始化
// 变量 "v" 只能由函数 "f()" 使用
// . 在调用这个文件中任何其他函数之前调用函数 "init()"
// 在你的程序最后调用函数 "cleanup()"
// 不要使用函数 "weird()"
// 函数 "f()"有两个参数

如果是正常地使用C++，这种注释一般都应该认为是不必要的。例如，人们可以根据连接规则（9.2节）以及类的可见性、初始化和清理规则（10.4.1节）来说明上面的注释例子完全是多余的。

  一旦某些东西已经在语言里说清楚了，就不应该在注释里第二次提它。例如，

    a = b + c;        // a 变成 b + c
    count++;          // count 加 1

这种注释比多余还要坏。它们增加了读者必须去看的正文数量，也使程序结构变得更模糊。而且它们还可能是错的。注意，无论如何，这类注释被广泛地用在程序设计语言的教科书里，例如这一本书里。这也是在教科书里的程序与真实程序之间的众多差异之一。

  我的偏爱在于：

1）、为每一个源文件写一个注释，一般性地陈述在它里面有哪些声明，对于有关手册的引用，为维护而提供的一般性提示，如此等等。
2）、对每个类、模版和名字空间写一个注释。
3）、对每个非平凡的函数写一个注释，陈述其用途，所用的算法（除非算法非常明显），以及可能有的关于它对于环境所做的假设。
4）、对每个全局和名字空间的变量和常量写一个注释。
5）、在非明显和／或不可移植的代码处的少量注释。
6）、极少其他的东西。

例如，

    // tbl.c:Implementation of the symbol table.
    /*
        Gaussian elimination with partial pivoting.
        See Ralston: "A first course ..." pg 411.
    */
    // swap() assumes the stack layout of an SGUI R6000
    /****************************
        Copyright(c) 1997 AT&T,Inc.
        All rights reserved
    *****************************/

一组经过良好选择和良好书写的注释是好程序中最具本质性的一个组成部分。写出好注释可能就像写出好程序一样困难，但这是一种值得好好修养的艺术。

  请再次注意，如果在一个函数里仅仅使用//形式的注释，那么这函数的任何部分都可以通过/* */风格的注释去掉，反过来也一样。

🔚